home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 21 / AACD 21.iso / AACD / Programming / Scalos / Developer / Autodoc / preferences.doc < prev    next >
Encoding:
Text File  |  2000-09-03  |  16.2 KB  |  481 lines
  1. TABLE OF CONTENTS
  2.  
  3. preferences.library/--background--
  4. preferences.library/AllocPrefsHandle
  5. preferences.library/FindPreferences
  6. preferences.library/FreePrefsHandle
  7. preferences.library/GetEntry
  8. preferences.library/GetPreferences
  9. preferences.library/ReadPrefsHandle
  10. preferences.library/RemEntry
  11. preferences.library/SetEntry
  12. preferences.library/SetPreferences
  13. preferences.library/WritePrefsHandle
  14. preferences.library/--background--            preferences.library/--background--
  15.  
  16.    PURPOSE
  17.       The preferences.library provides a convenient way to store the
  18.       preferences for your program. All internal management and I/O of your
  19.       data is handled by the library, and is controlled via a simple interface
  20.       which makes use of identifiers and tags to access the data. Multiple
  21.       programs can access the data (held only once in memory) at the same time
  22.       as access is arbitrated through the use of semaphores.
  23.  
  24.    OVERVIEW
  25.       Most of the data and structures mentioned here will be unavailable to
  26.       the programmer, but it is useful to know, so that the correct use of the
  27.       library can be adhered to.
  28.  
  29.       * All accesses to a preferences structure must be made through a
  30.         "PrefsHandle". A PrefsHandle is accessed by name (maximum of 32
  31.         unique characters) using AllocPrefsHandle(). Within a PrefsHandle a
  32.         list of ID's within this handle is stored. The pointer remains valid
  33.         until you call FreePrefsHandle().
  34.  
  35.       * The ID's are the first level of separation of preference data. Each
  36.         ID must be 4 ASCII characters, for example "MAIN", or "MENU". For
  37.         creating the ID you can use the MAKE_ID macro as defined in
  38.         libraries/iffparse.h. ID's are unique within each PrefsHandle. This
  39.         means that you can have an ID "MAIN" within two PrefsHandle's
  40.         and they will be completely different ID's.
  41.  
  42.       * The second level of separating the data is to use tags. A tag can have
  43.         any value except 0. The data is stored along with the tag. Tags are
  44.         unique within an ID the same way an ID is unique within a PrefsHandle.
  45.  
  46.       This gives the following structure to preferences items:
  47.  
  48.                        Main list of all preferences handles
  49.                                /        |       \
  50.                 ______________/         |        \___________________
  51.                /                        |                            \
  52.           PrefsHandle              PrefsHandle      ...          PrefsHandle
  53.         _/          \_
  54.        /              \
  55.       ID        ______ID
  56.     _/ |\      /   __/ |\
  57.    /   | \    |   /   /  \         etc.
  58.   Tag+ | Tag+ | Tag+ | Tag+
  59.   Data | Data | Data | Data
  60.        |      |      |
  61.      Tag+   Tag+   Tag+
  62.      Data   Data   Data
  63.  
  64.  
  65.       The data can be manipulated in these structures using SetPreferences()
  66.       to set the data and GetPreferences() to retrieve the data.
  67.  
  68.  
  69.       There is an alternative way to store the data. You can also have a list
  70.       of data items for each tag value. NB: you cannot mix normal single data
  71.       tags and their functions with the list type tags and their functions.
  72.       This is achieved using SetEntry(), GetEntry() and RemEntry() functions.
  73.       Each data item in the list is accessed using a logical entry number.
  74.       Since the data items are not explicitly accessed using this entry
  75.       number (such as with an array), their positions can change when you add
  76.       items in the middle of the list. For this reason you cannot guarantee
  77.       the order of data items in this sub-list. Applications of this method of
  78.       storing data could be a list of files which your program runs at
  79.       startup, without needing them to be in any specific order.
  80.  
  81.  
  82.       FindPreferences() will return a pointer to the tag specified and can be
  83.       used to find whether a certain tag exists or to access the data (if you
  84.       know the internal structure of tag items :). This works for either
  85.       type of tag (single data item or list of data items).
  86.  
  87.       ReadPrefsHandle() and WritePrefsHandle() can be used to read or write an
  88.       entire PrefsHandle in the specified file.
  89.  
  90. preferences.library/AllocPrefsHandle        preferences.library/AllocPrefsHandle
  91.  
  92.    NAME
  93.       AllocPrefsHandle -- Allocate preferences handle
  94.  
  95.    SYNOPSIS
  96.       prefshandle = AllocPrefsHandle( name )
  97.       D0                             A0
  98.  
  99.       APTR AllocPrefsHandle( STRPTR );
  100.  
  101.    FUNCTION
  102.       Allocate a handle so that the preferences inside can be accessed. All
  103.       successful calls to this function must be matched by a call to the
  104.       FreePrefsHandle() function.
  105.  
  106.    INPUTS
  107.       name - a string that you can identify the preferences set by
  108.  
  109.    RESULT
  110.       prefshandle - a pointer to the newly allocated preferences set or NULL
  111.                     for failure.
  112.  
  113.    EXAMPLE
  114.  
  115.    NOTES
  116.  
  117.    BUGS
  118.  
  119.    SEE ALSO
  120.       FreePrefsHandle()
  121.  
  122. preferences.library/FindPreferences          preferences.library/FindPreferences
  123.  
  124.    NAME
  125.       FindPreferences -- get pointer to data stored for a preference tag
  126.  
  127.    SYNOPSIS
  128.       prefsstruct = FindPreferences(prefshandle, ID, Tag);
  129.       D0                            A0           D0  D1
  130.  
  131.       struct PrefsStruct *FindPreferences(APTR, ULONG, ULONG);
  132.  
  133.    FUNCTION
  134.       Searchs for the preferences entry specified by the preferences handle,
  135.       ID and Tag values and returns a pointer to whatever is stored there.
  136.       Similar to GetPreferences() and GetEntry(), but since it does not copy
  137.       any data can be used on both types of tag it can be used to find out
  138.       whether a tag is present in a PrefsHandle.
  139.  
  140.    INPUTS
  141.       PrefsHandle   - pointer to a previously successfully allocated
  142.                       preferences handle
  143.       ID            - id of the set within the preferences handle you wish to
  144.                       use
  145.       Tag           - the tag used to identify this preference data within the
  146.                       the ID set
  147.  
  148.    RESULT
  149.       prefsstruct - pointer to the preferences item if found, NULL otherwise
  150.  
  151.    EXAMPLE
  152.  
  153.    NOTES
  154.       The returned pointer will return a pointer to the tag item, which will
  155.       either be followed by the data (if set with SetPreferences()) or the
  156.       list of sub items (if set by SetEntry()).
  157.  
  158.    BUGS
  159.  
  160.    SEE ALSO
  161.       AllocPrefsHandle(), SetPreferences(), SetEntry(), GetPreferences(),
  162.       GetEntry()
  163.  
  164. preferences.library/FreePrefsHandle          preferences.library/FreePrefsHandle
  165.  
  166.    NAME
  167.       FreePrefsHandle -- free a previously allocated preferences handle
  168.  
  169.    SYNOPSIS
  170.       FreePrefsHandle(PrefsHandle);
  171.                       A0
  172.  
  173.       void FreePrefsHandle(APTR);
  174.  
  175.    FUNCTION
  176.       Frees the preferences set associated with the handle passed into this
  177.       function. This handle can ONLY be created by calling AllocPrefsHandle
  178.       successfully. You MUST NOT use this preferences handle after you free
  179.       it.
  180.  
  181.    INPUTS
  182.       PrefsHandle - pointer to the preferences handle successfully allocated
  183.                     using AllocPrefsHandle()
  184.  
  185.    RESULT
  186.  
  187.    EXAMPLE
  188.  
  189.    NOTES
  190.  
  191.    BUGS
  192.  
  193.    SEE ALSO
  194.       AllocPrefsHandle()
  195.  
  196. preferences.library/GetEntry                        preferences.library/GetEntry
  197.  
  198.    NAME
  199.       GetEntry -- fills in a user structure from a preferences item
  200.  
  201.    SYNOPSIS
  202.       bytescopied = GetEntry(PrefsHandle, ID, Tag, Struct, Struct_Size, Entry)
  203.       D0                     A0           D0  D1   A1      D2           D3
  204.  
  205.       ULONG GetEntry(APTR, ULONG, ULONG, APTR, UWORD, ULONG);
  206.  
  207.    FUNCTION
  208.       Copies the data stored in a preferences item to a struture or area of
  209.       memory supplied by the programmer. The preference item will come from
  210.       the list item at position "Entry" from the list in the Tag / ID /
  211.       preferences handle.
  212.  
  213.    INPUTS
  214.       PrefsHandle   - pointer to a previously successfully allocated
  215.                       preferences handle
  216.       ID            - id of the set within the preferences handle you wish to
  217.                       use
  218.       Tag           - the tag used to identify this preference data within the
  219.                       the ID set
  220.       Struct        - pointer to the structure/memory you wish to copy the
  221.                       preferences data to
  222.       Struct_Size   - size of the structure/memory
  223.       Entry         - the position in the Tag's entry list to read this data
  224.                       from
  225.  
  226.    RESULT
  227.       bytescopied - the actual number of bytes copied from the preference data
  228.                     to the structure/memory pointer.
  229.  
  230.    EXAMPLE
  231.  
  232.    NOTES
  233.       DO NOT MIX this command with Tag's which have had their preference data
  234.       set with SetPreferences. They are different internally. Only use this
  235.       with Tag's used with SetEntry.
  236.  
  237.    BUGS
  238.  
  239.    SEE ALSO
  240.       AllocPrefsHandle(), SetPreferences(), SetEntry()
  241.  
  242. preferences.library/GetPreferences            preferences.library/GetPreferences
  243.  
  244.    NAME
  245.       GetPreferences -- returns data from a preference item to the programmer
  246.  
  247.    SYNOPSIS
  248.       bytescopied = GetPreferences(PrefsHandle, ID, Tag, Struct, Struct_Size);
  249.       D0                           A0           D0  D1   A1      D2
  250.  
  251.       ULONG GetPreferences(APTR, ULONG, ULONG, APTR, UWORD);
  252.  
  253.    FUNCTION
  254.       Copies the data stored in a preferences item (as referenced the prefs
  255.       handle, ID and Tag values) into a structure/memory that the user passes.
  256.       The number of bytes actually copied will be returned.
  257.  
  258.    INPUTS
  259.       PrefsHandle   - pointer to a previously successfully allocated
  260.                       preferences handle
  261.       ID            - id of the set within the preferences handle you wish to
  262.                       use
  263.       Tag           - the tag used to identify this preference data within the
  264.                       the ID set
  265.       Struct        - pointer to the structure/memory you wish to store
  266.       Struct_Size   - size of the structure/memory
  267.  
  268.    RESULT
  269.  
  270.    EXAMPLE
  271.  
  272.    NOTES
  273.       This function does nothing if the ID and Tag values are 0, as they are
  274.       not considered valid as an ID or a Tag.
  275.  
  276.       This function assumes a single preferences item per tag, DO NOT USE IT
  277.       with preferences items set up with the "Entry" functions.
  278.  
  279.    BUGS
  280.  
  281.    SEE ALSO
  282.       AllocPrefsHandle(), SetPreferences()
  283.  
  284. preferences.library/ReadPrefsHandle          preferences.library/ReadPrefsHandle
  285.  
  286.    NAME
  287.       ReadPrefsHandle -- Load an entire prefs handle from disk
  288.  
  289.    SYNOPSIS
  290.       ReadPrefsHandle(PrefsHandle, Filename);
  291.                       A0           A1
  292.  
  293.       void ReadPrefsHandle(APTR, STRPTR);
  294.  
  295.    FUNCTION
  296.       Attempts to read data from a file on disk (previously saved with
  297.       WritePrefsHandle) into the specified preferences handle.
  298.  
  299.    INPUTS
  300.       PrefsHandle   - pointer to a previously allocated preferences handle
  301.       Filename      - full path and name of file to load from
  302.  
  303.    RESULT
  304.  
  305.    EXAMPLE
  306.  
  307.    NOTES
  308.       Data is stored in memory using SetPreferences() and SetEntry()
  309.       functions.
  310.  
  311.    BUGS
  312.       Should probably return a value to indicate whether file was read
  313.       successfully or not.
  314.  
  315.    SEE ALSO
  316.       AllocPrefsHandle(), WritePrefsHandle(), SetPreferences(), SetEntry()
  317.  
  318. preferences.library/RemEntry                        preferences.library/RemEntry
  319.  
  320.    NAME
  321.       RemEntry -- remove an preferences item entry from a Tag that has a list
  322.  
  323.    SYNOPSIS
  324.       success = RemEntry(PrefsHandle, ID, Tag, Entry);
  325.       D0                 A0           D0  D1   D2
  326.  
  327.       ULONG RemEntry(APTR, ULONG, ULONG, ULONG);
  328.  
  329.    FUNCTION
  330.       Removes a preferences item, that is in a list at position "Entry", at
  331.       the given preferences handle, ID and Tag locations.
  332.  
  333.    INPUTS
  334.       PrefsHandle   - pointer to a previously successfully allocated
  335.                       preferences handle
  336.       ID            - id of the set within the preferences handle you wish to
  337.                       use
  338.       Tag           - the tag used to identify this preference data within the
  339.                       the ID set
  340.       Entry         - the position in the Tag's entry list to read this data
  341.                       from
  342.  
  343.    RESULT
  344.       success - whether the entry was successfully removed or not.
  345.  
  346.    EXAMPLE
  347.  
  348.    NOTES
  349.       DO NOT MIX this function with Tag's which have been created with
  350.       SetPreferences.
  351.  
  352.    BUGS
  353.  
  354.    SEE ALSO
  355.       AllocPrefsHandle(), SetPreferences(), SetEntry()
  356.  
  357. preferences.library/SetEntry                        preferences.library/SetEntry
  358.  
  359.    NAME
  360.       SetEntry -- adds preference data to a list of entries related to the Tag
  361.  
  362.    SYNOPSIS
  363.       SetEntry(PrefsHandle, ID, Tag, Struct, Struct_Size, Entry)
  364.                A0           D0  D1   A1      D2           D3
  365.  
  366.       void SetEntry(APTR, ULONG, ULONG, APTR, UWORD, ULONG);
  367.  
  368.    FUNCTION
  369.       Stores some user data in the preferences item in the preferences handle,
  370.       under the specified ID and Tag values. It will be stored at position
  371.       "Entry" in a list of values being stored under the given Tag value.
  372.  
  373.    INPUTS
  374.       PrefsHandle   - pointer to a previously successfully allocated
  375.                       preferences handle
  376.       ID            - id of the set within the preferences handle you wish to
  377.                       use
  378.       Tag           - the tag used to identify this preference data within the
  379.                       the ID set
  380.       Struct        - pointer to the structure/memory you wish to store
  381.       Struct_Size   - size of the structure/memory
  382.       Entry         - the position in the Tag's entry list to store this data
  383.  
  384.    RESULT
  385.  
  386.    EXAMPLE
  387.  
  388.    NOTES
  389.       DO NOT MIX this command with Tag values which have been created with
  390.       SetPreferences. They are different internally. If you have previously
  391.       stored data in this PrefsHandle/ID/Tag/Entry combination, it will be
  392.       overwritten if the data sizes are the same, otherwise this new data will
  393.       be inserted at the position specified.
  394.  
  395.    BUGS
  396.       Since the entry can be added at the end of the list (if the position is
  397.       not found), this means that it can be added at a position not equal to
  398.       the given Entry value. This is not a bug as such, but the function
  399.       should probably return the actual position that it is inserted at. Also,
  400.       the function can fail (when allocating memory) so it should also return
  401.       a value to indicate that failure.
  402.  
  403.    SEE ALSO
  404.       AllocPrefsHandle(), SetPreferences()
  405.  
  406. preferences.library/SetPreferences            preferences.library/SetPreferences
  407.  
  408.    NAME
  409.       SetPreferences -- store data in a preference item
  410.  
  411.    SYNOPSIS
  412.       SetPreferences(PrefsHandle, ID, Tag, Struct, Struct_Size);
  413.                      A0,          D0, D1,  A1,     D2
  414.  
  415.       void SetPreferences(APTR, ULONG, ULONG, APTR, UWORD);
  416.  
  417.    FUNCTION
  418.       Stores a structure of data in the preferences handle, under the given
  419.       ID and tag values.
  420.  
  421.    INPUTS
  422.       PrefsHandle   - pointer to a previously successfully allocated
  423.                       preferences handle
  424.       ID            - id of the set within the preferences handle you wish to
  425.                       use
  426.       Tag           - the tag used to identify this preference data within the
  427.                       the ID set
  428.       Struct        - pointer to the structure/memory you wish to store
  429.       Struct_Size   - size of the structure/memory
  430.  
  431.    RESULT
  432.  
  433.    EXAMPLE
  434.  
  435.    NOTES
  436.       This function does nothing if the ID and Tag values are 0, as they are
  437.       not considered valid as an ID or a Tag. This will overwrite any data
  438.       that has previously been stored in this PrefsHandle/ID/Tag combination.
  439.  
  440.       This sets up a single preferences item for the given tag. DO NOT MIX
  441.       preferences created with this function with the "Entry" commands!!!
  442.  
  443.    BUGS
  444.  
  445.    SEE ALSO
  446.       AllocPrefsHandle()
  447.  
  448. preferences.library/WritePrefsHandle        preferences.library/WritePrefsHandle
  449.  
  450.    NAME
  451.       WritePrefsHandle -- saves an entire preferences handle to a file
  452.  
  453.    SYNOPSIS
  454.       WritePrefsHandle(PrefsHandle, Filename);
  455.                        A0           A1
  456.  
  457.       void WritePrefsHandle(APTR, STRPTR);
  458.  
  459.    FUNCTION
  460.       Stores all the data and structure of the preferences handle to a file
  461.       on disk.
  462.  
  463.    INPUTS
  464.       PrefsHandle - pointer to a previously allocated preferences handle
  465.       Filename    - full path and name of file to save to
  466.  
  467.    RESULT
  468.  
  469.    EXAMPLE
  470.  
  471.    NOTES
  472.       This function can deal with single or list entries for a Tag value.
  473.  
  474.    BUGS
  475.       Should probably return a value to show if the file was successfully
  476.       saved or not.
  477.  
  478.    SEE ALSO
  479.       AllocPrefsHandle(), ReadPrefsHandle()
  480.  
  481.